// SAX parser interface.
// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
// $Id: Parser.java,v 1.6 2002/01/30 21:13:47 dbrownell Exp $

package org.xml.sax;

import java.io.IOException;
import java.util.Locale;


/**
 * SAX（Simple API for XML）分析器的基本接口。
 *
 *已经过期，被{@link org.xml.sax.XMLReader XMLReader}替代
 *
 * 所有SAX1解析器都必须实现这个基本接口：它允许应用程序为不同类型的事件注册处理程序，并从URI或字符流开始解析。
 *
 * 所有的SAX1解析器也必须实现一个零参数的构造函数（尽管其他构造函数也是允许的）。
 *
 * SAX1解析器可重复使用但不可重入：一旦第一个解析成功完成，应用程序可以重用解析器对象（可能具有不同的输入源），
 * 但是它可能不会在解析中递归地调用parse（）方法。
 *
 * @deprecated 该接口已被SAX2 @link org.xml.sax.XMLReader XMLReader}接口取代，SAX2包含名称空间支持。
 * @since SAX 1.0
 * @author David Megginson
 * @version 2.0.1 (sax2r2)
 * @see org.xml.sax.EntityResolver
 * @see org.xml.sax.DTDHandler
 * @see org.xml.sax.DocumentHandler
 * @see org.xml.sax.ErrorHandler
 * @see org.xml.sax.HandlerBase
 * @see org.xml.sax.InputSource
 */
@Deprecated
public interface Parser
{

    /**
     * 允许应用程序请求区域错误和警告
     *
     * SAX解析器不需要提供本地化的错误和警告;
     * 如果他们不能支持所请求的语言环境，则必须抛出一个SAX异常。
     * 应用程序可能不会在解析过程中请求区域设置更改。
     *
     * @param locale Java语言环境对象
     * @exception org.xml.sax.SAXException 如果所请求的区域设置不受支持，则会引发异常（使用以前的或默认的区域设置）。
     * @see org.xml.sax.SAXException
     * @see org.xml.sax.SAXParseException
     */
    public abstract void setLocale (Locale locale)
    throws SAXException;


    /**
     * 允许应用程序注册一个自定义实体解析器。
     *
     * 如果应用程序没有注册实体解析器，则SAX解析器将解析系统标识符并打开与实体本身的连接（这是Handler Base中实现的默认行为）。
     *
     * 应用程序可以在解析中注册新的或不同的实体解析器，SAX解析器必须立即开始使用新的解析器。
     *
     * @param resolver The object for resolving entities.
     * @see EntityResolver
     * @see HandlerBase
     */
    public abstract void setEntityResolver (EntityResolver resolver);


    /**
     * 允许应用程序注册一个DTD事件处理程序。
     *
     * 如果应用程序没有注册DTD处理程序，那么SAX解析器报告的所有DTD事件将被忽略（这是HandlerBase实现的默认行为）。
     *
     * 应用程序可以在解析中注册一个新的或不同的处理程序，SAX解析器必须立即开始使用新的处理程序。
     *
     * @param handler The DTD handler.
     * @see DTDHandler
     * @see HandlerBase
     */
    public abstract void setDTDHandler (DTDHandler handler);


    /**
     * 允许应用程序注册文档事件处理程序。
     *
     * 如果应用程序没有注册文档处理程序，那么SAX解析器报告的所有文档事件将被默默忽略
     * （这是HandlerBase实现的默认行为）
     *
     * 应用程序可以在解析中注册一个新的或不同的处理程序，SAX解析器必须立即开始使用新的处理程序
     *
     * @param handler The document handler.
     * @see DocumentHandler
     * @see HandlerBase
     */
    public abstract void setDocumentHandler (DocumentHandler handler);


    /**
     * 允许应用程序注册错误事件处理程序
     *
     * 如果应用程序没有注册错误事件处理程序，则SAX解析器报告的所有错误事件将被忽略，
     * 除了致命的错误，这将引发SAXException（这是Handler Base实现的默认行为）。
     *
     * 应用程序可以在解析中注册一个新的或不同的处理程序，SAX解析器必须立即开始使用新的处理程序。
     *
     *
     * @param handler The error handler.
     * @see ErrorHandler
     * @see SAXException
     * @see HandlerBase
     */
    public abstract void setErrorHandler (ErrorHandler handler);


    /**
     * 解析一个XML文档。
     *
     * 应用程序可以使用此方法指示SAX解析器开始从任何有效的输入源（字符流，字节流或URI）解析XML文档，
     *
     * 应用程序可能不会在解析正在进行时调用此方法（它们应该为每个其他XML文档创建一个新的解析器）。
     *
     * 解析完成后，应用程序可能会重用相同的解析器对象，可能会使用不同的输入源
     *
     * @param source XML文档顶层的输入源
     * @exception org.xml.sax.SAXException 任何SAX异常，可能包装另一个异常。
     * @exception java.io.IOException 解析器的IO异常，可能来自应用程序提供的字节流或字符流。
     * @see org.xml.sax.InputSource
     * @see #parse(java.lang.String)
     * @see #setEntityResolver
     * @see #setDTDHandler
     * @see #setDocumentHandler
     * @see #setErrorHandler
     */
    public abstract void parse (InputSource source)
    throws SAXException, IOException;


    /**
     *从系统标识符（URI）解析XML文档。
     *
     * 此方法是从系统标识符读取文档的常见情况的捷径。
     * 这与以下内容完全相同：
     *
     * <pre>
     * parse(new InputSource(systemId));
     * </pre>
     *
     *如果系统标识符是一个URL，那么在传递给解析器之前，它必须由应用程序完全解析
     *
     * @param systemId 系统标识符（URI）
     * @exception org.xml.sax.SAXException 何SAX异常，可能包装另一个异常。
     * @exception java.io.IOException 解析器的IO异常，可能来自应用程序提供的字节流或字符流。
     * @see #parse(org.xml.sax.InputSource)
     */
    public abstract void parse (String systemId)
    throws SAXException, IOException;

}
